<html><head><title>InsertElement</title></head>
<body bgcolor="#EFF1F0" link="#3A3966" vlink="#000000" alink="#000000">
<font face="Verdana, sans-serif" size="2"><p align="center"><b><font size="4">InsertElement()</font></b></p>
<p><b>Syntax</b></p><blockquote>
Result = <font color="#3A3966"><b>InsertElement</b></font>(List()) </blockquote>

</blockquote>
<b>Description</b><br><blockquote>

Inserts a new empty element before the current element, or at the start of the list 
if the list is empty (i.e. has no elements in it). This new element becomes 
the current element of the list. 

</blockquote><p><b>Parameters</b></p><blockquote>
<style type="text/css">
table.parameters { border-spacing: 0px; border-style: none; border-collapse: collapse; }
table.parameters td { border-width: 1px; padding: 6px; border-style: solid; border-color: gray; vertical-align: top; font-family:Arial; font-size:10pt; }
</style>
<table width="90%" class="parameters">
<tr><td width="10%"><i>List()</i></td>
<td width="90%"> 
The name of your list variable, created with the <a href="../reference/newlist.html">NewList</a> function. 
You must include the brackets after the list name. 

</td></tr>
</table>
</blockquote><p><b>Return value</b></p><blockquote>

Returns non-zero if the new element was created and zero otherwise. The value returned is 
a <a href="../reference/memory.html">pointer</a> to the new element data. 

</blockquote><p><b>Example</b></p><blockquote>

<pre><font face="Courier New, Courier, mono"size="2">  <font color="#3A3966">; The simplest way to use InsertElement</font>
  <b><font color="#3A3966">NewList</font></b> <font color="#3A3966">simple</font>.w()
<font color="#3A3966">  InsertElement</font>(<font color="#3A3966">simple</font>())    <font color="#3A3966">; Creates the first new element in the list</font>
<font color="#3A3966">  simple</font>() = 23

<font color="#3A3966">  InsertElement</font>(<font color="#3A3966">simple</font>())    <font color="#3A3966">; Current position is the first element, so we add this element to the start of the list</font>
<font color="#3A3966">  simple</font>() = 45              <font color="#3A3966">; The old first element is now the second element in the list</font>


  <font color="#3A3966">; This shows how to use the return-value of InsertElement</font>
  <b><font color="#3A3966">NewList</font></b> <font color="#3A3966">advanced</font>.l()
  <b><font color="#3A3966">If</font></b> <font color="#3A3966">InsertElement</font>(<font color="#3A3966">advanced</font>()) &lt;&gt; 0
<font color="#3A3966">    advanced</font>() = 12345
  <b><font color="#3A3966">Else</font></b>
<font color="#3A3966">    MessageRequester</font>(&quot;Error!&quot;, &quot;Unable to allocate memory for new element&quot;, <font color="#924B72">#PB_MessageRequester_OK</font>)
  <b><font color="#3A3966">EndIf</font></b>


  <font color="#3A3966">; A small structure to demonstrate the use of the pointer to the new element</font>
  <b><font color="#3A3966">Structure</font></b> Programmer
    Name.s
    Strength.b
  <b><font color="#3A3966">EndStructure</font></b>

  <b><font color="#3A3966">NewList</font></b> <font color="#3A3966">Programmers</font>.Programmer()  <font color="#3A3966">; The list for storing the elements</font>

  *Element.Programmer =<font color="#3A3966"> InsertElement</font>(<font color="#3A3966">Programmers</font>())
  <b><font color="#3A3966">If</font></b> *Element&lt;&gt;0
    *Element\Name = &quot;Dave&quot;
    *Element\Strength = 3   <font color="#3A3966">; Wow, super-strong geek! ;)</font>
  <b><font color="#3A3966">Else</font></b>
<font color="#3A3966">    MessageRequester</font>(&quot;Error!&quot;, &quot;Unable to allocate memory for new element&quot;, <font color="#924B72">#PB_MessageRequester_OK</font>)
  <b><font color="#3A3966">EndIf</font></b>
</font></pre>

</blockquote><p><b>See Also</b></p><blockquote>

<a href="addelement.html">AddElement()</a>, <a href="deleteelement.html">DeleteElement()</a>, <a href="clearlist.html">ClearList()</a> 

</Blockquote><p><b>Supported OS </b><Blockquote>All</Blockquote></p><center><- <a href=freelist.html>FreeList()</a> - <a href="index.html">List Index</a> - <a href="lastelement.html">LastElement()</a> -><br><br>

</body></html>